<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>HTTP Relay 💡</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Beast">
<link rel="up" href="../more_examples.html" title="HTTP Examples">
<link rel="prev" href="head_response_server.html" title="HEAD response (Server) 💡">
<link rel="next" href="send_child_process_output.html" title="Send Child Process Output 💡">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="head_response_server.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../more_examples.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="send_child_process_output.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="beast.more_examples.http_relay"></a><a class="link" href="http_relay.html" title="HTTP Relay 💡">HTTP Relay 💡</a>
</h3></div></div></div>
<p>
        An HTTP proxy acts as a relay between client and server. The proxy reads
        a request from the client and sends it to the server, possibly adjusting
        some of the headers and representation of the body along the way. Then, the
        proxy reads a response from the server and sends it back to the client, also
        with the possibility of changing the headers and body representation.
      </p>
<p>
        The example that follows implements a synchronous HTTP relay. It uses a fixed
        size buffer, to avoid reading in the entire body so that the upstream connection
        sees a header without unnecessary latency. This example brings together all
        of the concepts discussed so far, it uses both a <a class="link" href="../ref/boost__beast__http__serializer.html" title="http::serializer"><code class="computeroutput"><span class="identifier">serializer</span></code></a> and a <a class="link" href="../ref/boost__beast__http__parser.html" title="http::parser"><code class="computeroutput"><span class="identifier">parser</span></code></a> to achieve its goal:
      </p>
<pre class="programlisting"><span class="comment">/** Relay an HTTP message.

    This function efficiently relays an HTTP message from a downstream
    client to an upstream server, or from an upstream server to a
    downstream client. After the message header is read from the input,
    a user provided transformation function is invoked which may change
    the contents of the header before forwarding to the output. This may
    be used to adjust fields such as Server, or proxy fields.

    @param output The stream to write to.

    @param input The stream to read from.

    @param buffer The buffer to use for the input.

    @param transform The header transformation to apply. The function will
    be called with this signature:
    @code
        template&lt;class Body&gt;
        void transform(message&lt;
            isRequest, Body, Fields&gt;&amp;,  // The message to transform
            error_code&amp;);               // Set to the error, if any
    @endcode

    @param ec Set to the error if any occurred.

    @tparam isRequest `true` to relay a request.

    @tparam Fields The type of fields to use for the message.
*/</span>
<span class="keyword">template</span><span class="special">&lt;</span>
    <span class="keyword">bool</span> <span class="identifier">isRequest</span><span class="special">,</span>
    <span class="keyword">class</span> <span class="identifier">SyncWriteStream</span><span class="special">,</span>
    <span class="keyword">class</span> <span class="identifier">SyncReadStream</span><span class="special">,</span>
    <span class="keyword">class</span> <span class="identifier">DynamicBuffer</span><span class="special">,</span>
    <span class="keyword">class</span> <span class="identifier">Transform</span><span class="special">&gt;</span>
<span class="keyword">void</span>
<span class="identifier">relay</span><span class="special">(</span>
    <span class="identifier">SyncWriteStream</span><span class="special">&amp;</span> <span class="identifier">output</span><span class="special">,</span>
    <span class="identifier">SyncReadStream</span><span class="special">&amp;</span> <span class="identifier">input</span><span class="special">,</span>
    <span class="identifier">DynamicBuffer</span><span class="special">&amp;</span> <span class="identifier">buffer</span><span class="special">,</span>
    <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">,</span>
    <span class="identifier">Transform</span><span class="special">&amp;&amp;</span> <span class="identifier">transform</span><span class="special">)</span>
<span class="special">{</span>
    <span class="keyword">static_assert</span><span class="special">(</span><span class="identifier">is_sync_write_stream</span><span class="special">&lt;</span><span class="identifier">SyncWriteStream</span><span class="special">&gt;::</span><span class="identifier">value</span><span class="special">,</span>
        <span class="string">"SyncWriteStream requirements not met"</span><span class="special">);</span>

    <span class="keyword">static_assert</span><span class="special">(</span><span class="identifier">is_sync_read_stream</span><span class="special">&lt;</span><span class="identifier">SyncReadStream</span><span class="special">&gt;::</span><span class="identifier">value</span><span class="special">,</span>
        <span class="string">"SyncReadStream requirements not met"</span><span class="special">);</span>

    <span class="comment">// A small buffer for relaying the body piece by piece</span>
    <span class="keyword">char</span> <span class="identifier">buf</span><span class="special">[</span><span class="number">2048</span><span class="special">];</span>

    <span class="comment">// Create a parser with a buffer body to read from the input.</span>
    <span class="identifier">parser</span><span class="special">&lt;</span><span class="identifier">isRequest</span><span class="special">,</span> <span class="identifier">buffer_body</span><span class="special">&gt;</span> <span class="identifier">p</span><span class="special">;</span>

    <span class="comment">// Create a serializer from the message contained in the parser.</span>
    <span class="identifier">serializer</span><span class="special">&lt;</span><span class="identifier">isRequest</span><span class="special">,</span> <span class="identifier">buffer_body</span><span class="special">,</span> <span class="identifier">fields</span><span class="special">&gt;</span> <span class="identifier">sr</span><span class="special">{</span><span class="identifier">p</span><span class="special">.</span><span class="identifier">get</span><span class="special">()};</span>

    <span class="comment">// Read just the header from the input</span>
    <span class="identifier">read_header</span><span class="special">(</span><span class="identifier">input</span><span class="special">,</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">ec</span><span class="special">);</span>
    <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span>
        <span class="keyword">return</span><span class="special">;</span>

    <span class="comment">// Apply the caller's header transformation</span>
    <span class="identifier">transform</span><span class="special">(</span><span class="identifier">p</span><span class="special">.</span><span class="identifier">get</span><span class="special">(),</span> <span class="identifier">ec</span><span class="special">);</span>
    <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span>
        <span class="keyword">return</span><span class="special">;</span>

    <span class="comment">// Send the transformed message to the output</span>
    <span class="identifier">write_header</span><span class="special">(</span><span class="identifier">output</span><span class="special">,</span> <span class="identifier">sr</span><span class="special">,</span> <span class="identifier">ec</span><span class="special">);</span>
    <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span>
        <span class="keyword">return</span><span class="special">;</span>

    <span class="comment">// Loop over the input and transfer it to the output</span>
    <span class="keyword">do</span>
    <span class="special">{</span>
        <span class="keyword">if</span><span class="special">(!</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">is_done</span><span class="special">())</span>
        <span class="special">{</span>
            <span class="comment">// Set up the body for writing into our small buffer</span>
            <span class="identifier">p</span><span class="special">.</span><span class="identifier">get</span><span class="special">().</span><span class="identifier">body</span><span class="special">().</span><span class="identifier">data</span> <span class="special">=</span> <span class="identifier">buf</span><span class="special">;</span>
            <span class="identifier">p</span><span class="special">.</span><span class="identifier">get</span><span class="special">().</span><span class="identifier">body</span><span class="special">().</span><span class="identifier">size</span> <span class="special">=</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">buf</span><span class="special">);</span>

            <span class="comment">// Read as much as we can</span>
            <span class="identifier">read</span><span class="special">(</span><span class="identifier">input</span><span class="special">,</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">p</span><span class="special">,</span> <span class="identifier">ec</span><span class="special">);</span>

            <span class="comment">// This error is returned when buffer_body uses up the buffer</span>
            <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span> <span class="special">==</span> <span class="identifier">error</span><span class="special">::</span><span class="identifier">need_buffer</span><span class="special">)</span>
                <span class="identifier">ec</span> <span class="special">=</span> <span class="special">{};</span>
            <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span>
                <span class="keyword">return</span><span class="special">;</span>

            <span class="comment">// Set up the body for reading.</span>
            <span class="comment">// This is how much was parsed:</span>
            <span class="identifier">p</span><span class="special">.</span><span class="identifier">get</span><span class="special">().</span><span class="identifier">body</span><span class="special">().</span><span class="identifier">size</span> <span class="special">=</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">buf</span><span class="special">)</span> <span class="special">-</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">get</span><span class="special">().</span><span class="identifier">body</span><span class="special">().</span><span class="identifier">size</span><span class="special">;</span>
            <span class="identifier">p</span><span class="special">.</span><span class="identifier">get</span><span class="special">().</span><span class="identifier">body</span><span class="special">().</span><span class="identifier">data</span> <span class="special">=</span> <span class="identifier">buf</span><span class="special">;</span>
            <span class="identifier">p</span><span class="special">.</span><span class="identifier">get</span><span class="special">().</span><span class="identifier">body</span><span class="special">().</span><span class="identifier">more</span> <span class="special">=</span> <span class="special">!</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">is_done</span><span class="special">();</span>
        <span class="special">}</span>
        <span class="keyword">else</span>
        <span class="special">{</span>
            <span class="identifier">p</span><span class="special">.</span><span class="identifier">get</span><span class="special">().</span><span class="identifier">body</span><span class="special">().</span><span class="identifier">data</span> <span class="special">=</span> <span class="keyword">nullptr</span><span class="special">;</span>
            <span class="identifier">p</span><span class="special">.</span><span class="identifier">get</span><span class="special">().</span><span class="identifier">body</span><span class="special">().</span><span class="identifier">size</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
        <span class="special">}</span>

        <span class="comment">// Write everything in the buffer (which might be empty)</span>
        <span class="identifier">write</span><span class="special">(</span><span class="identifier">output</span><span class="special">,</span> <span class="identifier">sr</span><span class="special">,</span> <span class="identifier">ec</span><span class="special">);</span>

        <span class="comment">// This error is returned when buffer_body uses up the buffer</span>
        <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span> <span class="special">==</span> <span class="identifier">error</span><span class="special">::</span><span class="identifier">need_buffer</span><span class="special">)</span>
            <span class="identifier">ec</span> <span class="special">=</span> <span class="special">{};</span>
        <span class="keyword">if</span><span class="special">(</span><span class="identifier">ec</span><span class="special">)</span>
            <span class="keyword">return</span><span class="special">;</span>
    <span class="special">}</span>
    <span class="keyword">while</span><span class="special">(!</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">is_done</span><span class="special">()</span> <span class="special">&amp;&amp;</span> <span class="special">!</span> <span class="identifier">sr</span><span class="special">.</span><span class="identifier">is_done</span><span class="special">());</span>
<span class="special">}</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie
      Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="head_response_server.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../more_examples.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="send_child_process_output.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
